Copyright: Copyright (c) 1995 Okino Computer Graphics, Inc.


Wavefront OBJ Geometry Import Converter

This geometry import converter reads in Wavefront 'OBJ' format files in their entirety, including vertex, normal and texture coordinates, as well as grouping and smoothing information. Many companies which sell 3D models provide their datasets in the OBJ file format, so you can use this converter to read in these data files and be guaranteed nice rendered results.

The converter will also read material definitions from a Wavefront material file (typically which has a file extension '.mtl') if the material file is referenced within the Wavefront geometry file (typically which has a file extension '.obj') using the 'mtllib' keyword. If one or more Wavefront material files are listed on a single line then all will be read into memory for possible reference by the geometry file.

The converter first reads the entire file into memory; this includes the vertex, normal and texture coordinate lists, their indice lists, all group names, material names and texture names, and the smoothing groups assigned to each polygon. Next, the converter computes new vertex normals for polygons that don't have any normals and that have a non-zero smoothing group assigned to them. If no smoothing groups are found then the converter optionally creates smoothed vertex normals based on the angle between abutting polygon faces. As a last step, the polygonal data is separated into separate objects based on a user-chosen criteria.

NOTES:

1.	If any texture map names are found in the file ('usemap <map_name>') and the 'Use Material Name' dialog box option is enabled then texture definitions will be automatically created for these texture names and will be assigned to their corresponding surfaces. NOTE:: you can distinguish these textured surfaces because the texture map name is appended to the end of the surface name (the surface and texture names are separated by three underscores '_').

2.	If one or more group names are found on a 'g' line, then they are appended all together to form the group name used internally (ie: 'g all airplane tail_fin').

Dialog Box Options:

The following information explains the various options on the dialog box:

Compute normals using assigned smoothing groups

If this checkbox is enabled then new vertex normals will be computed for a polygon if it does not have any vertex normals already and it has been assigned a non-zero smoothing group number. Two abutting polygons will appear to be smooth only if they share common vertices.

Compute averaged normals

If this checkbox is enabled then new vertex normals will be computed for a polygon if it does not have any vertex normals already, and it does not have a smoothing group assigned to it or the 'Compute normals using assigned smoothing groups' checkbox is disabled. The smoothing criterion is based on the angle between abutting polygons; common smoothed vertex normals will be computed if the angle between their geometric surfaces normals is less than the angle specified on the dialog box (which defaults to 30 degrees).

Report statistics about the geometry file

If this checkbox is enabled then statistics about the geometry file will be reported once it has been read in and processed.

Print warning messages

If this checkbox is enabled then warning messages will be reported as the file is read in. Warnings include unrecognized input and options, out-of-range texture coordinates and out-of-range index values.

Source for the Surface Name

This option specifies which method the converter is to use to assign a surface definition to each polygon. Automatic assignment of surfaces to the polygons will save you a lot of time and headache.

Use material name, else group names if no materials found

The surface name will be taken from the material name assigned to each polygon. If no materials are found in the file then the surface name will be taken from the group name assigned to each polygon. ace name will be taken from the material name assigned to each polygon. If no group names are assigned to the polygons then the surface name will be taken from the object name assigned to each polygon. If no material, group or object name is assigned then the "default" surface will be used.

This is the default method.

Use material names found in file, else "default" surface if no materials

This will use the material name associated with each polygon as the surface name. If no material name is assigned then the "default" surface will be used.

Use group names found in file, else "default" surface if no groups

This will use the group name associated with each polygon as the surface name. If no group name is assigned then the "default" surface will be used.

Use object names found in file, else "default" surface if no objects

This will use the object name associated with each polygon as the surface name. If no object name is assigned then the "default" surface will be used.

Method for Splitting Polygons

This option selects which criterion is to be used when the polygonal data is to be split up into different objects. If your 3D scene is going to have many different objects in it then it is recommended that the OBJ not be split up. However, if you want to modify each individual part in the OBJ file then you will want to split it up into different objects.

Don't split into different objects

This option prevents the OBJ file from being split up into separate objects.

Split by object name

This will split the polygonal geometry according to the object name assigned to each polygon.

Objects are assigned to polygons in the OBJ file by preceding them with a line like: 'o <object_name> ... <object_name>'.

Split by group name

This will split the polygonal geometry according to the group name assigned to each polygon. It is the most logical method for splitting the geometry since the group names are usually assigned on an object-name basis by the person who designed the 3D model.

Groups are assigned to polygons in the OBJ file by preceding them with a line like: 'g <group_name1> ... <group_nameN>'.

Split by material name

This will split the polygonal geometry according to the material name assigned to each polygon. You may want to use this method if no group names are provided in the file or if it makes more sense to split by material name than by group name (for example, the object might have 300 odd group names but 20 carefully chosen material names).

Materials are assigned to polygons in the OBJ file by preceding them with a line like: 'usemtl <material_name>'.

Split by texture map name

This will split the polygonal geometry according to the texture map name assigned to each polygon. In most cases you will not use this method.

Texture map names are assigned to polygons in the OBJ file by preceding them with a line like: 'usemap <texture_map_name>'.

Split by smoothing group numbers

This will split the polygonal geometry according to the smoothing group number assigned to each polygon. Since smoothed polygons are usually clustered together as one sub-object this method can be used to accurately extract sub-objects from the polygonal data. However, it will probably create many more new objects than would the 'Split by group name' method above.

Smoothing groups are assigned to polygons in the OBJ file by preceding them with a line like: 's <smoothing_number>'.